Fill gaps from assistant conversations: rail webhooks, missed events, shipments filter, map local testing by mintlify[bot] · Pull Request #301 · Terminal49/API

mintlify · 2026-07-20T16:08:56Z

Summary

Close four recurring documentation gaps surfaced by recent assistant conversation buckets, so future readers can self-serve without needing the assistant to infer missing steps.

Changes

Rail Integration Guide — added a "Set up a webhook for rail events" subsection with a concrete POST /webhooks example, the Rail Plan entitlement note, and a callout that container.transport.rail_arrived fires at every intermediate rail terminal.
Webhooks best practices — added a "Recover events you were never subscribed to" subsection clarifying that re-fetching returns the current state only (not intermediate history), and that Trigger Webhook is a test tool, not a replay mechanism.
List shipments (OpenAPI) — expanded the number query parameter description to state that it matches request_number (BOL / booking), not container numbers, and points to the containers endpoint for container-number lookups.
Terminal49 Map Embed guide — added a short Note confirming local development (opening the file directly or serving from localhost) works, provided the CDN assets and a valid publishable API key are reachable.

Context

Sourced from the 2026-07-13 → 2026-07-20 assistant query buckets; verified against the existing docs and OpenAPI spec before editing.

Greptile Summary

This PR fills several documentation gaps around webhooks, shipment lookup, and map testing. The main changes are:

Adds rail webhook setup and event details.
Explains recovery limits for events missed before subscription.
Clarifies shipment-number filtering and container lookup.
Documents local map-embed testing.

Confidence Score: 4/5

The container-number lookup guidance needs correction before merging.

The recommended containers request uses an undefined filter and can return an error or unfiltered results.
The direct-file map claim depends on CORS support that is not stated in the guide.
The new rail webhook and missed-event guidance matches the documented API shapes.

docs/openapi.json and docs/api-docs/in-depth-guides/terminal49-map.mdx

Important Files Changed

Filename	Overview
docs/api-docs/in-depth-guides/rail-integration-guide.mdx	Adds a valid rail webhook example, entitlement details, event behavior, and signature guidance.
docs/api-docs/webhooks/best-practices.mdx	Explains that late subscriptions cannot recover historical notifications or intermediate state.
docs/api-docs/in-depth-guides/terminal49-map.mdx	Adds local testing guidance, but direct file-origin support depends on the map API's CORS behavior.
docs/openapi.json	Clarifies the shipment number filter but recommends a container filter absent from the documented operation.

Prompt To Fix All With AI

Fix the following 2 code review issues. Work through them one at a time, proposing concise fixes.

---

### Issue 1 of 2
docs/openapi.json:605
**Container Lookup Uses Unsupported Filter**

A client following this description will call `GET /containers?filter[number]=...`, but the containers operation does not define that parameter and the typed SDK cannot emit it. The server may reject the request or ignore the filter and return a paginated list instead of the requested container; the documented cross-resource lookup for container numbers is `/search?query=...`.

### Issue 2 of 2
docs/api-docs/in-depth-guides/terminal49-map.mdx:23-25
**File-Origin Support Is Unqualified**

Loading the hosted script and stylesheet does not prove that the embed works from `file://`: requests made by the bundle use the browser's `null` origin and fail unless the map API explicitly permits it. If that API only allows normal HTTP origins, the assets load but the map remains blank, so this claim should be limited to verified origins or state the required CORS support.

_{Reviews (1): Last reviewed commit: "docs: fill gaps from assistant conversat..." | Re-trigger Greptile}

Greptile also left 2 inline comments on this PR.

…vents, shipments filter, map local testing)

vercel · 2026-07-20T16:09:02Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
api	Building	Preview, Comment	Jul 20, 2026 4:09pm

mintlify · 2026-07-20T16:09:48Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
terminal49	🟢 Ready	View Preview	Jul 20, 2026, 4:10 PM

greptile-apps · 2026-07-20T16:11:11Z

            "in": "query",
            "name": "number",
-            "description": "Search shipments by the original request tracking `request_number`"
+            "description": "Search shipments by the original tracking `request_number` — typically a master bill of lading or booking number. This filter does **not** match container numbers; to look up a shipment by container number, use `GET /containers?filter[number]={container_number}` and include the related shipment via `include=shipment`."


Container Lookup Uses Unsupported Filter

A client following this description will call GET /containers?filter[number]=..., but the containers operation does not define that parameter and the typed SDK cannot emit it. The server may reject the request or ignore the filter and return a paginated list instead of the requested container; the documented cross-resource lookup for container numbers is /search?query=....

Prompt To Fix With AI

This is a comment left during a code review. Path: docs/openapi.json Line: 605 Comment: **Container Lookup Uses Unsupported Filter** A client following this description will call `GET /containers?filter[number]=...`, but the containers operation does not define that parameter and the typed SDK cannot emit it. The server may reject the request or ignore the filter and return a paginated list instead of the requested container; the documented cross-resource lookup for container numbers is `/search?query=...`. How can I resolve this? If you propose a fix, please make it concise.

greptile-apps · 2026-07-20T16:11:12Z

+<Note>
+  The map embed works from a local development environment. Open your HTML file directly in a browser or serve it from `http://localhost` — there is no domain allowlisting on the embed itself. Your page just needs internet access to load `bundle.js` and `bundle.css` from `https://map.terminal49.com`, and a valid publishable API key.
+</Note>


File-Origin Support Is Unqualified

Loading the hosted script and stylesheet does not prove that the embed works from file://: requests made by the bundle use the browser's null origin and fail unless the map API explicitly permits it. If that API only allows normal HTTP origins, the assets load but the map remains blank, so this claim should be limited to verified origins or state the required CORS support.

Prompt To Fix With AI

This is a comment left during a code review. Path: docs/api-docs/in-depth-guides/terminal49-map.mdx Line: 23-25 Comment: **File-Origin Support Is Unqualified** Loading the hosted script and stylesheet does not prove that the embed works from `file://`: requests made by the bundle use the browser's `null` origin and fail unless the map API explicitly permits it. If that API only allows normal HTTP origins, the assets load but the map remains blank, so this claim should be limited to verified origins or state the required CORS support. How can I resolve this? If you propose a fix, please make it concise.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!

docs: fill gaps from assistant conversations (rail webhooks, missed e…

e1358ad

…vents, shipments filter, map local testing)

mintlify Bot merged commit 3fa77c9 into main Jul 20, 2026
9 of 10 checks passed

vercel Bot deployed to Preview July 20, 2026 16:09 View deployment

greptile-apps Bot reviewed Jul 20, 2026

View reviewed changes

Navigation Menu

Uh oh!

Fill gaps from assistant conversations: rail webhooks, missed events, shipments filter, map local testing - #301

Fill gaps from assistant conversations: rail webhooks, missed events, shipments filter, map local testing#301
mintlify[bot] merged 1 commit into
mainfrom
mintlify/8004abc0

mintlify Bot commented Jul 20, 2026 •

edited by greptile-apps Bot

Loading

Uh oh!

vercel Bot commented Jul 20, 2026

Uh oh!

Uh oh!

mintlify Bot commented Jul 20, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot Jul 20, 2026

Uh oh!

greptile-apps Bot Jul 20, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

0 participants

Uh oh!

Conversation

mintlify Bot commented Jul 20, 2026 • edited by greptile-apps Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Context

Greptile Summary

Confidence Score: 4/5

Important Files Changed

Uh oh!

vercel Bot commented Jul 20, 2026

Uh oh!

Uh oh!

mintlify Bot commented Jul 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

greptile-apps Bot Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

greptile-apps Bot Jul 20, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

0 participants

mintlify Bot commented Jul 20, 2026 •

edited by greptile-apps Bot

Loading

mintlify Bot commented Jul 20, 2026 •

edited

Loading